Inside Macintosh: QuickTime Components
Derived media handlers provide three functions that allow the Movie Toolbox to manage its relationship with the media handler. The Movie Toolbox calls your MediaInitialize function in order to give you an opportunity to prepare to provide access to your media. The Movie Toolbox grants processing time to your handler by calling your MediaIdle function. Your MediaGGetStatus function allows the Movie Toolbox to retrieve status information after calling MediaIdle .
The MediaInitialize function allows your derived media handler component to prepare itself for providing access to its media.
pascal ComponentResult MediaInitialize (MediaHandler mh,
GetMovieCompleteParams *gmc);
Once the Movie Toolbox has loaded a movie's data from its file, the toolbox calls your derived media handler's MediaInitialize function. If the user is creating a new movie, the Movie Toolbox calls your media handler anyway, even though there may be no media data.
This function gives your media handler an opportunity to get ready to support the Movie Toolbox. As part of these preparations, your derived media handler should report its capabilities to the base media handler by calling the MediaSetHandlerCapabilities function (see MediaSetHandlerCapabilities for more information about this function).
You may choose to examine the data in the movie parameter structure; you may also save values from this structure. If you save references to structures (such as the matte pixel map), do not dispose of the memory associated with these structures. The Movie Toolbox owns these structures.
All derived media handlers should support this function. In addition, if your media handler saves values from the movie parameter structure that may change, be sure to support the corresponding functions that allow the Movie Toolbox to report changes to your media handler. For example, if your handler saves the movie time scale from the movieScale field, you should also support the MediaSetMovieTimeScale function.
If you return an error, the Movie Toolbox disables the track that uses your media. In cases where your media has just been created, the Movie Toolbox immediately disposes of your media.
Note that the Movie Toolbox may call other functions supported by your media handler before it calls your MediaInitialize function. In particular, it may call your MediaGetMediaInfo and MediaPutMediaInfo functions. However, before the Movie Toolbox tries to do anything with the data in your media, it will call your MediaInitialize function. The Movie Toolbox loads the movie's data using functions that are supported by the base media handler--your media handler does not have to support those functions.
The MediaIdle function allows the Movie Toolbox to provide processing time to your derived media handler during movie playback. Your media handler may use this time to play its media.
pascal ComponentResult MediaIdle (MediaHandler mh,
TimeValue atMediaTime,
long flagsIn, long *flagsOut,
const TimeRecord *movieTime);
The Movie Toolbox uses your MediaIdle function to provide processing time to your derived media handler during movie playback. Your media handler is free to use this time in any appropriate manner. For example, if your media handler supports a sound data type, you might prepare to play your media's sounds or actually play them, depending upon the options asserted by the Movie Toolbox. Your media handler is responsible for limiting the amount of processing time it uses.
The Movie Toolbox provides the current time, in your media's time base, in the atMediaTime parameter. You can use this value to obtain the appropriate samples and sample descriptions from your media (using the Movie Toolbox's GetMediaSample function). Your media handler may then work with the sample data and descriptions as appropriate.
If you encounter an error, save the result code. The Movie Toolbox polls you for status information using the MediaGGetStatus function, which is described next.
Your handler should examine the flagsIn parameter each time the Movie Toolbox calls its MediaIdle function. The flags in this parameter indicate the actions that your handler may perform. In addition, when you return from your MediaIdle function, you should report what you did using the flagsOut parameter. You tell the base media handler that you perform your own scheduling by setting the handlerNoScheduler flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function (see MediaSetHandlerCapabilities for more information about this function).
If your media handler changes any of the settings of the movie's graphics port or graphics world, be sure to restore the original settings before you exit. In addition, note that you may be drawing into a black-and-white graphics port. Finally, be aware that the Movie Toolbox also uses this function to obtain data for QuickDraw pictures. Therefore, if your media handler does not use QuickDraw when drawing to the screen, be sure to examine the picSave field in the graphics port so that you can detect when the toolbox wants to save an image. Your media handler is then responsible for performing the appropriate display processing. (For details on QuickDraw pictures, see the chapter "Basic QuickDraw" in Inside Macintosh: Imaging .)
Your derived media handler should support this function if you need to do work during movie playback. If you set the handlerNoIdle flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function, the Movie Toolbox does not call your MediaIdle function.
The MediaGGetStatus function allows your derived media handler to report error conditions to the Movie Toolbox.
pascal ComponentResult MediaGGetStatus (MediaHandler mh,
ComponentResult *statusErr);
The Movie Toolbox calls your MediaGGetStatus function whenever an application calls the toolbox's GetMovieStatus or GetTrackStatus function. This provides your media handler an opportunity to report any difficulties it may be having in playing your media. You should use this mechanism to report any errors you encounter in your MediaIdle function (described in the previous section). You may use any appropriate result code.
Your derived media handler should support this function if you anticipate that you may encounter an error when playing your media. Because these errors may include such conditions as low memory or missing hardware, you should only rarely create a derived media handler that does not support this function. If your media handler does not support this function, the base media handler always sets the returned result code to noErr .